<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>InputBox</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>InputBox</h1>

<p>Displays an input box to ask the user to enter a string.</p>

<pre class="Syntax">InputBox, OutputVar [, Title, Prompt, HIDE, Width, Height, X, Y, Font, Timeout, Default]</pre>
<h3>Parameters</h3>
<dl>

  <dt>OutputVar</dt>
  <dd><p>The name of the variable in which to store the text entered by the user.</p></dd>

  <dt>Title</dt>
  <dd><p>The title of the input box. If blank or omitted, it defaults to the name of the script.</p></dd>

  <dt>Prompt</dt>
  <dd><p>The text of the input box, which is usually a message to the user indicating what kind of input is expected. If <em>Prompt</em> is long, it can be broken up into several shorter lines by means of a <a href="../Scripts.htm#continuation">continuation section</a>, which might improve readability and maintainability.</p></dd>

  <dt>HIDE</dt>
  <dd><p>If this parameter is the word HIDE, the user's input will be masked, which is useful for passwords.</p></dd>

  <dt>Width</dt>
  <dd><p>If this parameter is blank or omitted, the starting width of the window will be 375. This parameter can be an <a href="../Variables.htm#Expressions">expression</a>.</p></dd>

  <dt>Height</dt>
  <dd><p>If this parameter is blank or omitted, the starting height of the window will be 189. This parameter can be an <a href="../Variables.htm#Expressions">expression</a>.</p></dd>

  <dt>X, Y</dt>
  <dd><p>The X and Y coordinates of the window (use 0,0 to move it to the upper left corner of the desktop), which can be <a href="../Variables.htm#Expressions">expressions</a>. If either coordinate is blank or omitted, the dialog will be centered in that dimension. Either coordinate can be negative to position the window partially or entirely off the desktop.</p></dd>

  <dt>Font</dt>
  <dd><p>Not yet implemented (leave blank). In the future it might accept something like verdana:8</p></dd>

  <dt>Timeout</dt>
  <dd><p>Timeout in seconds (can contain a decimal point or be an <a href="../Variables.htm#Expressions">expression</a>). If this value exceeds 2147483 (24.8 days), it will be set to 2147483. After the timeout has elapsed, the InputBox window will be automatically closed and <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to 2. <em>OutputVar</em> will still be set to what the user entered.</p></dd>

  <dt>Default</dt>
  <dd><p>A string that will appear in the InputBox's edit field when the dialog first appears. The user can change it by backspacing or other means.</p></dd>

</dl>
<h3>ErrorLevel</h3>
<p><span class="ver">[v1.1.04+]</span> This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<p>See below.</p>
<h3>Remarks</h3>
<p>The dialog allows the user to enter text and then press OK or CANCEL. The user can resize the dialog window by dragging its borders.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if the user presses the CANCEL button, 0 if the user presses OK, or 2 if the dialog times out. In all three cases, <em>OutputVar</em> is set to the value entered. This allows the CANCEL button to perform a function other than CANCEL should the script designer wish it.</p>
<p>A GUI window may display a modal InputBox by means of <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a>. A modal InputBox prevents the user from interacting with the GUI window until the InputBox is dismissed.</p>
<h3>Related</h3>
<p><a href="Gui.htm">GUI</a>, <a href="Input.htm">Input</a>, <a href="MsgBox.htm">MsgBox</a>, <a href="FileSelectFile.htm">FileSelectFile</a>, <a href="FileSelectFolder.htm">FileSelectFolder</a>, <a href="SplashTextOn.htm">SplashTextOn</a>, <a href="ToolTip.htm">ToolTip</a></p>
<h3>Example</h3>
<pre class="NoIndent">InputBox, password, Enter Password, (your input will be hidden), hide 
InputBox, UserInput, Phone Number, Please enter a phone number., , 640, 480
if ErrorLevel
    MsgBox, CANCEL was pressed.
else
    MsgBox, You entered &quot;%UserInput%&quot;</pre>

</body>
</html>
